Documentation

inbox/Missing ADRs Analysis.md

Missing ADRs Analysis - Acsis Core Polylith .NET Monorepo

Analysis Date

August 4, 2025

Overview

This document identifies architectural decisions in the Acsis Core repository that should have ADRs but are currently missing. The analysis was conducted by examining the codebase, configuration files, and patterns used throughout the system.

Existing ADRs (Already Documented)

  • ADR-001: Polylith Architecture adoption
  • ADR-002: .Spec naming convention
  • ADR-003: Dynamic component loading with AssemblyLoadContext
  • ADR-004: Roslyn analyzer enforcement (ACSIS0001)
  • ADR-005: .slnx solution format adoption
  • ADR-006: Directory.Build.props centralization

Missing ADRs Identified

Technology Stack & Framework Choices

ADR-007: .NET 9.0 Adoption with Latest C# Features

  • Decision: Adopt .NET 9.0 as the target framework across all components with LangVersion set to "latest"
  • Evidence: All .csproj files specify <TargetFramework>net9.0</TargetFramework> and <LangVersion>latest</LangVersion>
  • Significance: Early adoption of latest .NET version impacts deployment targets, available APIs, and development tooling requirements
  • Priority: High - Affects entire development and deployment strategy

ADR-008: Microsoft Enterprise Library Data Adoption

  • Decision: Use Enterprise Library Data for database operations instead of pure Entity Framework
  • Evidence: EnterpriseLibrary.Data.NetCore package referenced throughout components, extensive use of DataTable and DataSet objects
  • Significance: Significant architectural choice affecting all database operations, potentially for legacy compatibility or enterprise requirements
  • Priority: High - Core data access pattern affects all components

ADR-009: Dual Authentication Strategy (JWT + Custom Token)

  • Decision: Implement both JWT Bearer authentication and custom "acsistoken" header authentication
  • Evidence: Program.cs configures JWT Bearer, but AcsisTokenAuthenticationHandler implements custom token validation
  • Significance: Supporting dual authentication mechanisms adds complexity but provides flexibility for different client types
  • Priority: High - Security-critical architectural decision

ADR-010: OpenTelemetry Integration for Observability

  • Decision: Integrate OpenTelemetry for distributed tracing and observability
  • Evidence: OpenTelemetry configuration in Program.cs with service identification
  • Significance: Forward-thinking approach to observability that affects monitoring and debugging
  • Priority: Medium - Important for operations but not core business logic

API Design & HTTP Patterns

ADR-011: Flexible API Versioning Strategy

  • Decision: Use combination of URL segment, header, and media type versioning with default version 5.0
  • Evidence: Program.cs configures ApiVersionReader.Combine() with multiple versioning strategies
  • Significance: Flexible versioning approach allows different client preferences but adds complexity
  • Priority: High - Affects API evolution and client compatibility

ADR-012: MediatR Pattern for Request/Response Handling

  • Decision: Use MediatR for implementing CQRS-like patterns and pipeline behaviors
  • Evidence: MediatR registration in Program.cs, pipeline behaviors for validation/performance/error handling
  • Significance: Decouples request handling from controllers and enables cross-cutting concerns
  • Priority: High - Fundamental request processing pattern

ADR-013: Standardized Pipeline Behaviors

  • Decision: Implement validation, performance monitoring, and exception handling as MediatR pipeline behaviors
  • Evidence: ValidationBehavior, PerformanceBehaviour, UnhandledExceptionBehaviour in HTTP component
  • Significance: Centralizes cross-cutting concerns but requires understanding of MediatR pipeline
  • Priority: Medium - Important for understanding request processing flow

ADR-014: Container-Aware CORS Configuration

  • Decision: Enable CORS only when running in containers with specific NextJS origins
  • Evidence: DOTNET_RUNNING_IN_CONTAINER environment variable check in Program.cs
  • Significance: Environment-specific behavior affects deployment and development workflows
  • Priority: Medium - Deployment-specific but important for understanding environment differences

Data Access & Persistence Patterns

ADR-015: Hybrid Data Access Strategy (EF Core + Enterprise Library)

  • Decision: Use Entity Framework Core for some operations (FileServiceDbContext) but Enterprise Library Data for most data access
  • Evidence: Both EF Core and Enterprise Library packages, mixture of DbContext and DataTable usage
  • Significance: Unusual hybrid approach suggesting migration in progress or specific requirements
  • Priority: High - Explains data access inconsistencies across components

ADR-016: Static Database Configuration Management

  • Decision: Use static DbConfig class for centralized connection string management
  • Evidence: DbConfig.cs with static properties and SetConfiguration method
  • Significance: Makes testing difficult and creates tight coupling to configuration
  • Priority: Medium - Technical debt that should be documented

ADR-017: DataTable/DataSet as Primary Data Transfer Objects

  • Decision: Use DataTable and DataSet for complex data operations instead of strongly-typed objects
  • Evidence: Extensive use throughout CoreDataApi for schema building and data manipulation
  • Significance: Performance-oriented but type-unsafe approach that affects development experience
  • Priority: High - Fundamental data handling pattern

Security & Authentication Decisions

ADR-018: Custom Encryption for Token Serialization

  • Decision: Implement custom AES encryption for sensitive token data with hardcoded keys
  • Evidence: Hardcoded IV and key in CoreDataApi.cs, custom encryption/decryption methods
  • Significance: Security-critical decision affecting token security and key management
  • Priority: High - Security implications need clear documentation

ADR-019: Comprehensive Permission System Architecture

  • Decision: Implement granular permission system with application-level, resource-level, and context restrictions
  • Evidence: Complex permission models in Identity component, permission validation in core-data
  • Significance: Enterprise-grade security model affecting all component interactions
  • Priority: High - Core security architecture

ADR-020: Session-Based User Context Management

  • Decision: Maintain user sessions with ticket IDs and location context for audit trails
  • Evidence: UserToken structure with TicketID, LocationID, and session management in IdentityApi
  • Significance: Enables detailed audit trails but increases complexity
  • Priority: Medium - Important for understanding user context handling

Serialization & Data Format Decisions

ADR-021: System.Text.Json with Source Generation

  • Decision: Use System.Text.Json with source generation for performance-critical serialization
  • Evidence: CoreDataSerializationContext with JsonSourceGeneration attributes
  • Significance: Modern, high-performance approach but requires compile-time type knowledge
  • Priority: Medium - Performance optimization with development implications

ADR-022: Reference Cycle Handling Strategy

  • Decision: Configure JSON serialization to ignore cycles rather than preserve references
  • Evidence: ReferenceHandler.IgnoreCycles in Program.cs JSON options
  • Significance: Prevents serialization errors but may lose data relationships
  • Priority: Medium - Important for understanding data serialization behavior

ADR-023: Custom Enum Serialization with EnumMember Support

  • Decision: Implement custom enum converter that respects EnumMember attributes
  • Evidence: JsonEnumToStringConverter and DictionaryLookupNamingPolicy classes
  • Significance: Provides flexibility for API contracts but adds serialization complexity
  • Priority: Low - Nice-to-have for API consistency

Validation & Error Handling Patterns

ADR-024: FluentValidation as Primary Validation Strategy

  • Decision: Use FluentValidation for all input validation across components
  • Evidence: Extensive AbstractValidator implementations across components, ValidationBehavior pipeline
  • Significance: Consistent validation approach but requires understanding of FluentValidation patterns
  • Priority: Medium - Consistent validation pattern across system

ADR-025: Centralized Exception Handling with Request Context

  • Decision: Handle exceptions in MediatR pipeline with request-specific logging
  • Evidence: UnhandledExceptionBehaviour logs request type and details
  • Significance: Provides good debugging information but requires structured logging
  • Priority: Medium - Important for troubleshooting and debugging

ADR-026: Performance Monitoring with Configurable Thresholds

  • Decision: Monitor request performance with 500ms threshold for warnings
  • Evidence: PerformanceBehaviour logs requests exceeding 500ms with user context
  • Significance: Proactive performance monitoring but threshold might need tuning
  • Priority: Low - Performance monitoring implementation detail

Event Handling & Integration Patterns

ADR-027: Azure Event Grid for External Event Publishing

  • Decision: Use Azure Event Grid for publishing events to external systems
  • Evidence: EventGridClient usage in EventsApi for external event publishing
  • Significance: Cloud-specific choice affecting deployment environments and event reliability
  • Priority: High - Cloud architecture decision with vendor lock-in implications

ADR-028: Notification Preference Management System

  • Decision: Implement user-configurable notification preferences for transit events
  • Evidence: UserTransitNotificationPreferences and related models in Events component
  • Significance: Enterprise feature adding complexity but improving user experience
  • Priority: Medium - Business feature with architectural implications

Build System & Development Workflow Decisions

ADR-029: MSBuild Property-Based Component References

  • Decision: Use MSBuild properties in Directory.Build.props for component paths instead of NuGet packages
  • Evidence: All component references use $(ComponentSpec) properties defined in Directory.Build.props
  • Significance: Enables monorepo development but creates non-standard reference patterns
  • Priority: High - Fundamental to understanding build system

ADR-030: Post-Build Component Assembly Copying

  • Decision: Copy component assemblies to bin/components for runtime loading
  • Evidence: CopyComponents MSBuild target in foundation project
  • Significance: Enables dynamic loading but requires specific build order and deployment considerations
  • Priority: Medium - Important for understanding build and deployment process

ADR-031: Nullable Reference Types Enforcement

  • Decision: Enable nullable reference types across all components
  • Evidence: <Nullable>enable</Nullable> in all .csproj files
  • Significance: Improves code safety but requires careful null handling throughout codebase
  • Priority: Medium - Development experience and code quality decision

File Handling & Content Management

ADR-032: Strict File Type Validation Strategy

  • Decision: Implement comprehensive file validation with explicit whitelist of allowed types
  • Evidence: FileValidator with specific MIME types and extension checking
  • Significance: Security-focused approach preventing malicious uploads but may be restrictive
  • Priority: Medium - Security decision with usability implications

ADR-033: Dual Interface Approach for File Service

  • Decision: Separate download and upload operations into distinct interfaces (IDownloaderApi/IUploaderApi)
  • Evidence: File service component has separate interfaces for upload and download operations
  • Significance: Clear separation of concerns but increases interface count
  • Priority: Low - Interface design pattern

Logging & Diagnostics Decisions

ADR-034: Structured Logging with User Context

  • Decision: Include user context (username, ticket ID, profile) in all log entries
  • Evidence: GetDataForAzMon method in IdentityApi, context-aware logging in behaviors
  • Significance: Enables detailed audit trails but requires careful PII handling
  • Priority: Medium - Important for compliance and troubleshooting

Priority Recommendations

High Priority ADRs (Should be written first):

  1. ADR-007: .NET 9.0 Adoption
  2. ADR-008: Enterprise Library Data Adoption
  3. ADR-009: Dual Authentication Strategy
  4. ADR-011: API Versioning Strategy
  5. ADR-012: MediatR Pattern Adoption
  6. ADR-015: Hybrid Data Access Strategy
  7. ADR-017: DataTable/DataSet as DTOs
  8. ADR-018: Custom Token Encryption
  9. ADR-019: Permission System Architecture
  10. ADR-027: Azure Event Grid Integration
  11. ADR-029: MSBuild Property-Based References

Medium Priority ADRs (Important for completeness):

  1. ADR-010: OpenTelemetry Integration
  2. ADR-013: Pipeline Behaviors
  3. ADR-014: Container-Aware CORS
  4. ADR-016: Static Database Configuration
  5. ADR-020: Session-Based User Context
  6. ADR-021: JSON Source Generation
  7. ADR-022: Reference Cycle Handling
  8. ADR-024: FluentValidation Strategy
  9. ADR-025: Centralized Exception Handling
  10. ADR-028: Notification Preferences
  11. ADR-030: Component Assembly Copying
  12. ADR-031: Nullable Reference Types
  13. ADR-032: File Type Validation
  14. ADR-034: Structured Logging

Low Priority ADRs (Nice to have):

  1. ADR-023: Custom Enum Serialization
  2. ADR-026: Performance Monitoring Thresholds
  3. ADR-033: Dual File Service Interfaces

Next Steps

  1. Review and Prioritize: Review this list with the development team to confirm priorities and add any missing items
  2. Create ADR Templates: Use the existing ADR template format for consistency
  3. Assign Authors: Assign ADR creation to team members familiar with each architectural decision
  4. Schedule Reviews: Plan team reviews for high-priority ADRs before marking them as "Accepted"
  5. Update Documentation: Keep the ADR README updated as new ADRs are added

Notes

  • This analysis focused on architectural decisions visible in the current codebase
  • Some decisions may be implicit or documented elsewhere (design docs, tickets, etc.)
  • The priority recommendations are based on impact on development, deployment, and system understanding
  • Consider combining related ADRs if they represent parts of a larger architectural decision

Analysis conducted by: Claude Code Agent
Repository analyzed: /Users/dcastonguay/source/acsis/portfolio/acsis-core
Analysis scope: Complete codebase including bases, components, and configuration files